---
title: Cloud Credentials
description: Learn how to leverage Terrateam's authentication and authorization features
---

import { Steps } from '@astrojs/starlight/components';
import { Card } from '@astrojs/starlight/components';

Terrateam provides flexible authentication and authorization options for Terraform operations, allowing you to securely manage credentials and control access to your cloud resources. In this guide, we'll explore advanced workflows and configurations using Terrateam's OIDC integration, static credentials, and custom scripts for generating cloud credentials.

## OIDC (OpenID Connect)
Terrateam's OIDC integration enables secure authentication against cloud providers using short-lived, dynamically generated credentials. 

<Card title="Benefits of OIDC over Static Credentials">

- Uses short-lived credentials that are automatically issued and expire quickly, reducing the risk of leaks.
- Improves your security posture by eliminating long-lived credentials from your environment.
- Reduces the effort needed to manage and rotate static access keys.
- Lets you define specific access scopes per workflow to keep permissions tight.

</Card>

### Basic OIDC Configuration
To use OIDC with Terrateam, you need to configure the `oidc` step type in your configuration. A step type defines a specific action in your workflow, such as authentication, initialization, or execution of Terraform commands.

:::note[Storing Sensitive Values]
All sensitive values should be stored as [GitHub Secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) and referenced using the `${SECRET_NAME}` syntax. This ensures credentials are encrypted and only accessible during workflow execution.
:::

#### Workflows Example
```yaml
workflows:
  - tag_query: "dir:aws"
    plan:
      - type: oidc  # Authentication step
        provider: aws
        role_arn: ${AWS_ROLE_ARN}
      - type: init  # Terraform initialization step
      - type: plan  # Terraform plan step
    apply:
      - type: oidc
        provider: aws
        role_arn: ${AWS_ROLE_ARN}
      - type: init
      - type: apply
```

#### Hooks Example
```yaml
hooks:
  all:
    pre:
      - type: oidc
        provider: aws
        role_arn: ${AWS_ROLE_ARN}
```

In these examples, OIDC is used to authenticate against AWS using the specified `role_arn`.

:::tip[Difference Between Hooks and Workflows]
Hooks are commands that run before or after all plan and apply steps, while workflows define the specific steps and sequence for each plan and apply operation.
:::

### Advanced OIDC Workflows
Terrateam's OIDC integration provides flexibility and customization options to suit your specific requirements. Here are some advanced OIDC workflows with examples:

#### Multiple OIDC Configurations
Define multiple OIDC configurations within a single workflow to use different roles or providers for different steps.
```yaml
workflows:
  - tag_query: "dir:aws"
    plan:
      - type: oidc
        provider: aws
        role_arn: ${AWS_PLAN_ROLE_ARN}
      - type: init
      - type: plan
    apply:
      - type: oidc
        provider: aws
        role_arn: ${AWS_APPLY_ROLE_ARN}
      - type: init
      - type: apply
```

In this example, the `plan` steps use a different IAM role (`AWS_PLAN_ROLE_ARN`) compared to the `apply` steps (`AWS_APPLY_ROLE_ARN`), allowing for granular permission control.

#### OIDC for Multiple Cloud Providers
Configure OIDC for different cloud providers, such as AWS and GCP, within the same workflow.
```yaml
workflows:
  - tag_query: "dir:multi-cloud"
    plan:
      - type: oidc
        provider: aws
        role_arn: ${AWS_ROLE_ARN}
      - type: oidc
        provider: gcp
        service_account: ${GCP_SERVICE_ACCOUNT}
        workload_identity_provider: ${GCP_WORKLOAD_IDENTITY_PROVIDER}
      - type: init
      - type: plan
    apply:
      - type: oidc
        provider: aws
        role_arn: ${AWS_ROLE_ARN}
      - type: oidc
        provider: gcp
        service_account: ${GCP_SERVICE_ACCOUNT}
        workload_identity_provider: ${GCP_WORKLOAD_IDENTITY_PROVIDER}
      - type: init
      - type: apply
```

This example demonstrates how to configure OIDC for both AWS and GCP within the same workflow, enabling multi-cloud deployments.

#### Conditional OIDC Configuration
Use Terrateam's tag queries and conditional expressions to selectively apply OIDC configurations based on specific criteria.
```yaml
workflows:
  - tag_query: "dir:aws/production"
    plan:
      - type: oidc
        provider: aws
        role_arn: ${AWS_PRODUCTION_ROLE_ARN}
      - type: init
      - type: plan
    apply:
      - type: oidc
        provider: aws
        role_arn: ${AWS_PRODUCTION_ROLE_ARN}
      - type: init
      - type: apply
  - tag_query: "dir:aws/staging"
    plan:
      - type: oidc
        provider: aws
        role_arn: ${AWS_STAGING_ROLE_ARN}
      - type: init
      - type: plan
    apply:
      - type: oidc
        provider: aws
        role_arn: ${AWS_STAGING_ROLE_ARN}
      - type: init
      - type: apply
```
In this example, different OIDC configurations are applied based on the `dir` tag, allowing for directory-specific roles and permissions.

## Static Credentials

:::caution[Security Consideration]
While static credentials are supported, we recommend using OIDC when possible for better security. Static credentials are long-lived and require manual rotation, increasing security risks.
:::

### Configuring Static Credentials

<Steps>
1. **Create GitHub Secrets**
   Store your credentials securely as GitHub Secrets:
   ```sh
   # Example for AWS credentials
   gh secret set AWS_ACCESS_KEY_ID --body "your-access-key"
   gh secret set AWS_SECRET_ACCESS_KEY --body "your-secret-key"
   ```

2. **Apply Least Privilege**
   Ensure the static credentials have minimal required permissions:
   ```yaml
   # Example AWS IAM policy
   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "s3:ListBucket",
           "s3:GetObject"
         ],
         "Resource": [
           "arn:aws:s3:::my-terraform-state",
           "arn:aws:s3:::my-terraform-state/*"
         ]
       }
     ]
   }
   ```
</Steps>

## Custom Credential Scripts

:::tip
When using custom credential scripts, ensure they:
- Generate credentials with minimal required permissions
- Expire credentials after the shortest practical duration
- Log credential usage for audit purposes
:::

### Configuring Custom Credential Scripts

<Steps>
1. Create your script
   ```bash
   #!/bin/bash
   # generate-aws-credentials.sh
   
   # Example script that generates temporary credentials
   environment=$1    # e.g., "production" or "staging"
   access_level=$2   # e.g., "read-only" or "read-write"
   
   # Generate credentials with appropriate permissions
   aws sts assume-role \
     --role-arn "arn:aws:iam::${AWS_ACCOUNT_ID}:role/${environment}-${access_level}" \
     --role-session-name "terrateam-${environment}"
   ```

2. Configure the Terrateam workflow
   ```yaml
   workflows:
     - tag_query: "dir:aws/production"
       plan:
         - type: env
           method: source
           cmd: ["./generate-aws-credentials.sh", "production", "read-only"]
         - type: init
         - type: plan
   ```

3. Set required permissions
   Make sure your script and the credentials it generates follow the principle of least privilege:
   - The script should only be allowed to assume specific roles.
   - The assumed credentials should have only the permissions necessary for their task.
   - Use separate permission sets for plan and apply operations.
</Steps>

## Best Practices
When implementing advanced authentication and authorization workflows with Terrateam, consider the following best practices:
- Principle of Least Privilege: Grant the minimum set of permissions required for each workflow or step, ensuring that credentials have access to only the necessary resources.
- Secure Credential Storage: Store sensitive credentials, such as static access keys or OIDC role ARNs, securely using GitHub Secrets or a secrets management system.
- Regular Credential Rotation: Implement a process to regularly rotate credentials, whether static or dynamically generated, to minimize the risk of unauthorized access.
